/*
 * Copyright 2011 The Rusted Roof, LLC.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

package org.proteusframework.platformservice.persistence.api;

import org.proteusframework.core.api.IDelegateConsumer;
import org.proteusframework.platformservice.persistence.vfs.FilePath;

import java.io.IOException;
import java.util.List;

/**
 * Virtual File System Manager.
 *
 * @author Tacoma Four
 */
public interface IVFSManager extends IDelegateConsumer
{
    //
    // File Persistence (Virtual File System)
    //

    /**
     * Flag that indicates if the persistence service supports a virtual file system.
     *
     * @return true, if VFS support is provided by the persistence service
     */
    boolean supportsVFSManagement();

    /**
     * Create a new file in the persistence service's virtual file system. This is the only supported way for
     * creating any file within the virtual file system. Once the <code>IVFSFile</code> has been created, access
     * the physical <code>File</code> or the absolute path of the <code>File</code> for native Java I/O operations.
     *
     * @param filePath File path to the new VFS file
     * @return Virtual file mapping for the specified path.
     */
    IVFSFile createFile(FilePath filePath);

    /**
     * Determines if the persistence store has a file at the given path.
     *
     * @param filePath File path
     * @return true, if a file exists at the given path
     */
    boolean hasFile(FilePath filePath);

    /**
     * Obtain a list of files under the directory represented by the file path.
     *
     * @param filePath File path that represents a directory.
     * @return Non-null list of files under the given file path directory
     * @throws IllegalArgumentException when the specified filePath is not a directory
     */
    List<IVFSFile> getFiles(FilePath filePath);

    /**
     * Gets the specific file pointed to by the file path.
     *
     * @param filePath File path to a specific file
     * @return Virtual file representation of the file at the target file path
     */
    IVFSFile getFile(FilePath filePath);

    /**
     * Remove the file from the persistence service's virtual file system, if it exists.
     *
     * @param vfsFile File to remove from the persistence store
     * @return true, if the file was successfully removed
     */
    boolean deleteFile(IVFSFile vfsFile);


    /**
     * Remove the file from the persistence service's virtual file system, if it exists.
     *
     * @param filePath File to remove from the persistence store
     * @return true, if the file was successfully removed
     */
    boolean deleteFile(FilePath filePath);

    /**
     * Accepts a VFS serializer visitor. The manager must iterate across each known IVFSFile, offering up each file to
     * the serialization visitor.
     *
     * @param visitor Serialization visitor
     */
    void accept(IVFSVisitor visitor) throws IOException;

}
